Feature: SDK Reference generation & hosting#78
Open
ben-fornefeld wants to merge 40 commits intomainfrom
Open
Conversation
- Updated the SDK generation workflow to load SDK configurations from `sdks.json`, improving maintainability. - Removed individual SDK generator scripts for CLI, Code Interpreter (JS and Python), and Desktop SDKs, consolidating functionality into a single generator script. - Enhanced the `generate-sdk-reference.sh` script to dynamically handle SDK types and versions. - Cleaned up the workflow YAML file for better readability and consistency in string formatting.
- Updated `.gitignore` to include `sdk_navigation.json` for generated SDK navigation. - Added new styles for version switcher in `style.css`, improving UI for SDK and version selection. - Modified `generate-sdk-nav.js` to group SDKs by family, enhancing navigation structure. - Updated SDK configurations in `sdks.json` to include family and language attributes for better organization. - Improved CLI and Python documentation generation scripts for consistency and added frontmatter to markdown files.
- Updated `sdk-reference-sync.yml` to allow version generation for "all" versions by default. - Modified `generate-sdk-reference.sh` to support a new `--limit` option for controlling the number of versions processed. - Improved `generate-sdk.sh` to filter versions based on a minimum version requirement and to handle version discovery more effectively. - Updated `sdks.json` to include `minVersion` attributes for SDKs, ensuring only compatible versions are processed. - Enhanced common library functions for version management and caching during dependency installation.
- Added verification functions to ensure generated documentation meets quality standards, including checks for empty files and missing frontmatter. - Implemented a logging utility for better output management during the generation process. - Created a `.mintignore` file to exclude specific directories from version control. - Enhanced CLI commands for improved user experience and added options for forced regeneration of existing versions.
- Introduced a new `sdks.config.ts` file to define SDK configurations in TypeScript, enhancing type safety and maintainability. - Removed the outdated `sdks.json` file to streamline the configuration process. - Updated relevant code to utilize the new configuration structure, including adjustments in the CLI and navigation logic. - Improved type definitions for SDK configurations to support additional properties and ensure consistency across the codebase.
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
- Updated CSS styles for version switcher to enhance UI consistency and usability. - Modified GitHub Actions workflow to streamline SDK generation input descriptions and improve summary output. - Refactored context handling in SDK generation functions for better clarity and maintainability. - Introduced new utility functions for version validation and normalization, enhancing version management. - Added tests for cache handling and file processing to ensure robustness in SDK reference generation.
- Deleted `package.json` and `pnpm-lock.yaml` files to clean up the project structure as they are no longer needed for SDK reference generation.
- Replaced `basePackage` and `fallbackPackages` with `allowedPackages` in SDK configurations for better clarity and usage. - Refactored the `generateVersion` function to utilize a new `CheckoutManager` for handling repository checkouts and version switching. - Simplified the `generatePydoc` function to focus on allowed packages, removing the need for fallback and submodule handling. - Introduced a new `checkout.ts` file to manage SDK checkouts, enhancing code organization and maintainability. - Removed obsolete cache handling code and related tests to streamline the project structure.
- Enhanced error handling in the CLI to ensure proper exit on validation failures. - Improved logging for workflow abort scenarios in the generator, ensuring clearer output. - Introduced a new function to find the CLI output directory, enhancing the generation process and error reporting for missing markdown files.
…dd versioning documentation
dobrac
requested changes
Jan 13, 2026
docs.json
Outdated
| "default": true, | ||
| "pages": [ | ||
| "docs/sdk-reference/js-sdk/v2.9.0/errors", | ||
| "docs/sdk-reference/js-sdk/v2.9.0/sandbox", |
Contributor
There was a problem hiding this comment.
do you have any mechanism for checking if all the urls are correct for SEO?
Member
Author
There was a problem hiding this comment.
this is an edge case, it should be always in sync but these entries are dev artifacts that i forgot to clean up
Member
Author
There was a problem hiding this comment.
we could add another workflow tho that checks on pr's
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes and found 1 potential issue.
Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.
| echo "No changes to commit" | ||
| echo "changes=false" >> $GITHUB_OUTPUT | ||
| else | ||
| git commit -m "docs: update SDK reference for $SDK_NAME $SDK_VERSION" |
There was a problem hiding this comment.
Commit message missing documented [skip ci] safety tag
Medium Severity
The README lists "Skips CI on doc updates ([skip ci] in commit message)" as a safety feature, but the actual git commit message in the workflow is "docs: update SDK reference for $SDK_NAME $SDK_VERSION" without any [skip ci] tag. Every automated documentation commit will trigger any push-based CI workflows in the repository, causing unnecessary CI runs and potentially triggering deployment pipelines.
Additional Locations (1)
jakubno
approved these changes
Feb 16, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Note
Medium Risk
Adds new automation that writes and commits generated docs and updates
docs.json; failures or config mistakes could overwrite navigation or publish incorrect reference content despite added verification and tests.Overview
Adds a new
sdk-reference-generatorTypeScript tool (with unit tests) to generate versioned SDK reference docs for multiple SDKs (TypeDoc, Python viapydoc-markdown, and CLI), normalize outputs to Mintlify-compatible.mdx, build/merge versioned navigation intodocs.json, and verify generated content before completion.Introduces two GitHub Actions workflows: a PR test workflow for the generator, and a manual/dispatchable sync workflow that runs generation with parameters (
sdk,version,limit,force), installs Node+Python deps, and auto-commitsdocs/sdk-reference/*anddocs.jsonwhen changes exist. Also adds supporting repo hygiene (.gitignore,.mintignore,requirements.txt).Written by Cursor Bugbot for commit d8bde74. This will update automatically on new commits. Configure here.